home *** CD-ROM | disk | FTP | other *** search
/ Mac Format 1995 June / MacFormat 25.iso / Shareware City / Developers / ICProgKit1.0 / Source / API Source / ICAPI.p next >
Text File  |  1994-11-27  |  10KB  |  269 lines
  1. unit ICAPI;
  2.  
  3. interface
  4.  
  5.     uses
  6. {$ifc undefined THINK_Pascal}
  7.         Types, Files, 
  8. {$endc}
  9.         ICTypes;
  10.  
  11.     function ICStart (var inst: ICInstance; creator: OSType): ICError;
  12.     (* call at application initialisation *)
  13.  
  14.     function ICStop (inst: ICInstance): ICError;
  15.     (* call at application termination *)
  16.  
  17.     function ICFindConfigFile (inst: ICInstance; count: integer; folders: ICDirSpecArrayPtr): ICError;
  18.     (* count is the number of ICDirSpecs that are valid in folders *)
  19.     (* searches the specified folders first, then backs out to preferences folder *)
  20.     (* don't you worry about how it finds the file (; *)
  21.     (* you can pass nil to folders if count is 0 *)
  22.  
  23.     function ICSpecifyConfigFile (inst: ICInstance; config: FSSpec): ICError;
  24.     (* for use *only* by Internet Configuration application *)
  25.  
  26.     function ICGetSeed (inst: ICInstance; var seed: longint): ICError;
  27.     (* returns current seed for prefs file *)
  28.     (* this seed changes every time a preference is modified *)
  29.     (* poll this to detect preference changes by other applications *)
  30.  
  31.     function ICGetPerm (inst: ICInstance; var perm: ICPerm): ICError;
  32.     (* returns the permissions currently associated with this file *)
  33.     (* mainly used by overriding components, applications normally *)
  34.     (* know what permissions they have *)
  35.     
  36.     function ICBegin (inst: ICInstance; perm: ICPerm): ICError;
  37.     (* start reading/writing the preferences *)
  38.     (* must be balanaced by a ICEnd *)
  39.     (* do not call WaitNextEvent between this pair *)
  40.     (* specify either icReadOnlyPerm or icReadWritePerm *)
  41.     (* note that this may open resource files and leave them open until ICEnd *)
  42.  
  43.     function ICGetPref (inst: ICInstance; key: Str255; var attr: ICAttr; buf: Ptr; var size: longint): ICError;
  44.     (* this routine may be called without a ICBegin/ICEnd pair, in which case *)
  45.     (* it implicitly calls ICBegin(inst, icReadOnlyPerm *)
  46.     (* given a key string, returns the attributes and the (optionally) the data for a preference *)
  47.     (* key must not be the empty string *)
  48.     (* if buf is nil then no data fetched and incoming size is ignored*)
  49.     (* size must be non-negative, is size of allocated space for data at buf *)
  50.     (* attr and size and always set on return *)
  51.     (* size is actual size of data (if key present) *)
  52.     (* attr is pref attributes *)
  53.      (* if icTruncatedErr then everything is valid, except you lost some data, size is size of real data*)
  54.     (* on other errors, attr is ICattr_no_change and size is 0 *)
  55.  
  56.     function ICSetPref (inst: ICInstance; key: Str255; attr: ICAttr; buf: Ptr; size: longint): ICError;
  57.     (* this routine may be called without a ICBegin/ICEnd pair, in which case *)
  58.     (* it implicitly calls ICBegin(inst, icReadWritePerm *)
  59.     (* given a key string, sets the attributes and the data for a preference (either is optional) *)
  60.     (* key must not be the empty string *)
  61.     (* if buf is nil then no data stored and size is ignored, used for setting attr *)
  62.     (* size must be non-negative, is size of the data at buf to store *)
  63.     (* icPermErr if ICBegin was given icReadOnlyPerm *)
  64.     (* icPermErr if current attr is locked, new attr is locked and buf <> nil *)
  65.  
  66.     function ICCountPref (inst: ICInstance; var count: longint): ICError;
  67.     (* count total number of preferences *)
  68.     (* if error then count is 0 *)
  69.  
  70.     function ICGetIndPref (inst: ICInstance; n: longint; var key: Str255): ICError;
  71.     (* return the key of the Nth preference *)
  72.     (* n must be positive *)
  73.     (* icPrefNotFoundErr if n is beyond the last preference *)
  74.  
  75.     function ICDeletePref (inst: ICInstance; key: Str255): ICError;
  76.     (* delete the preference specified by key *)
  77.     (* key must not be the empty string *)
  78.     (* preference specified by key must be present *)
  79.     (* icPrefNotFoundErr if it isn't *)
  80.  
  81.     function ICEnd (inst: ICInstance): ICError;
  82.     (* stop reading/writing the preferences *)
  83.  
  84.     function ICDefaultFileName (inst: ICInstance; var name: Str63): ICError;
  85.     (* return the default file name *)
  86.     (* the component calls this routine to set up the default internet configuration file name*)
  87.     (* this allows this operation to be intercepted by a component that has captured us *)
  88.     (* it currently gets it from the component resource file *)
  89.     (* the glue version is hardwired *)
  90.  
  91.     function ICGetComponentInstance (inst: ICInstance; var component_inst: univ Ptr): ICError;
  92.     (* returns noErr and the component instance that we're talking to, if we're using the component *)
  93.     (* returns an error and nil if we're doing it with glue *)
  94.     (* univ Ptr rather than ComponentInstance so that you don't need Components.p *)
  95.     (* in order to use this file *)
  96.  
  97. implementation
  98.  
  99.     uses
  100. {$ifc undefined THINK_Pascal}
  101.         Components, Memory, 
  102. {$endc}
  103.         ICCAPI, ICRAPI;
  104.  
  105.     function ICStart (var inst: ICInstance; creator: OSType): ICError;
  106.         var
  107.             err: ICError;
  108.     begin
  109.         inst := NewPtr(sizeof(ICRRecord));
  110.         err := MemError;
  111.         if err = noErr then begin
  112.             err := ICCStart(ICRRecordPtr(inst)^.instance, creator);
  113.             if err <> noErr then begin
  114.                 err := ICRStart(ICRRecordPtr(inst)^, creator);
  115.             end; (* if *)
  116.             if err <> noErr then begin
  117.                 DisposePtr(inst);
  118.                 inst := nil;
  119.             end; (* if *)
  120.         end; (* if *)
  121.         ICStart := err;
  122.     end; (* ICStart *)
  123.  
  124.     function ICStop (inst: ICInstance): ICError;
  125.         var
  126.             err, err2: ICError;
  127.     begin
  128.         if ICRRecordPtr(inst)^.instance <> nil then begin
  129.             err := ICCStop(ICRRecordPtr(inst)^.instance);
  130.         end
  131.         else begin
  132.             err := ICRStop(ICRRecordPtr(inst)^);
  133.         end; (* if *)
  134.         DisposePtr(inst);
  135.         ICStop := err;
  136.     end; (* ICStop *)
  137.  
  138.     function ICFindConfigFile (inst: ICInstance; count: integer; folders: ICDirSpecArrayPtr): ICError;
  139.     begin
  140.         if ICRRecordPtr(inst)^.instance <> nil then begin
  141.             ICFindConfigFile := ICCFindConfigFile(ICRRecordPtr(inst)^.instance, count, folders);
  142.         end
  143.         else begin
  144.             ICFindConfigFile := ICRFindConfigFile(ICRRecordPtr(inst)^, count, folders);
  145.         end; (* if *)
  146.     end; (* ICFindConfigFile *)
  147.  
  148.     function ICSpecifyConfigFile (inst: ICInstance; config: FSSpec): ICError;
  149.     begin
  150.         if ICRRecordPtr(inst)^.instance <> nil then begin
  151.             ICSpecifyConfigFile := ICCSpecifyConfigFile(ICRRecordPtr(inst)^.instance, config);
  152.         end
  153.         else begin
  154.             ICSpecifyConfigFile := ICRSpecifyConfigFile(ICRRecordPtr(inst)^, config);
  155.         end; (* if *)
  156.     end; (* ICSpecifyConfigFile *)
  157.  
  158.     function ICGetSeed (inst: ICInstance; var seed: longint): ICError;
  159.     begin
  160.         if ICRRecordPtr(inst)^.instance <> nil then begin
  161.             ICGetSeed := ICCGetSeed(ICRRecordPtr(inst)^.instance, seed);
  162.         end
  163.         else begin
  164.             ICGetSeed := ICRGetSeed(ICRRecordPtr(inst)^, seed);
  165.         end; (* if *)
  166.     end; (* ICGetSeed *)
  167.  
  168.     function ICGetPerm (inst: ICInstance; var perm: ICPerm): ICError;
  169.     begin
  170.         if ICRRecordPtr(inst)^.instance <> nil then begin
  171.             ICGetPerm := ICCGetPerm(ICRRecordPtr(inst)^.instance, perm);
  172.         end
  173.         else begin
  174.             ICGetPerm := ICRGetPerm(ICRRecordPtr(inst)^, perm);
  175.         end; (* if *)
  176.     end; (* ICGetPerm *)
  177.     
  178.     function ICBegin (inst: ICInstance; perm: ICPerm): ICError;
  179.     begin
  180.         if ICRRecordPtr(inst)^.instance <> nil then begin
  181.             ICBegin := ICCBegin(ICRRecordPtr(inst)^.instance, perm);
  182.         end
  183.         else begin
  184.             ICBegin := ICRBegin(ICRRecordPtr(inst)^, perm);
  185.         end; (* if *)
  186.     end; (* ICBegin *)
  187.  
  188.     function ICGetPref (inst: ICInstance; key: Str255; var attr: ICAttr; buf: Ptr; var size: longint): ICError;
  189.     begin
  190.         if ICRRecordPtr(inst)^.instance <> nil then begin
  191.             ICGetPref := ICCGetPref(ICRRecordPtr(inst)^.instance, key, attr, buf, size);
  192.         end
  193.         else begin
  194.             ICGetPref := ICRGetPref(ICRRecordPtr(inst)^, key, attr, buf, size);
  195.         end; (* if *)
  196.     end; (* ICGetPref *)
  197.  
  198.     function ICSetPref (inst: ICInstance; key: Str255; attr: ICAttr; buf: Ptr; size: longint): ICError;
  199.     begin
  200.         if ICRRecordPtr(inst)^.instance <> nil then begin
  201.             ICSetPref := ICCSetPref(ICRRecordPtr(inst)^.instance, key, attr, buf, size);
  202.         end
  203.         else begin
  204.             ICSetPref := ICRSetPref(ICRRecordPtr(inst)^, key, attr, buf, size);
  205.         end; (* if *)
  206.     end; (* ICSetPref *)
  207.  
  208.     function ICCountPref (inst: ICInstance; var count: longint): ICError;
  209.     begin
  210.         if ICRRecordPtr(inst)^.instance <> nil then begin
  211.             ICCountPref := ICCCountPref(ICRRecordPtr(inst)^.instance, count);
  212.         end
  213.         else begin
  214.             ICCountPref := ICRCountPref(ICRRecordPtr(inst)^, count);
  215.         end; (* if *)
  216.     end; (* ICCountPref *)
  217.  
  218.     function ICGetIndPref (inst: ICInstance; n: longint; var key: Str255): ICError;
  219.     begin
  220.         if ICRRecordPtr(inst)^.instance <> nil then begin
  221.             ICGetIndPref := ICCGetIndPref(ICRRecordPtr(inst)^.instance, n, key);
  222.         end
  223.         else begin
  224.             ICGetIndPref := ICRGetIndPref(ICRRecordPtr(inst)^, n, key);
  225.         end; (* if *)
  226.     end; (* ICGetIndPref *)
  227.  
  228.     function ICDeletePref (inst: ICInstance; key: Str255): ICError;
  229.     begin
  230.         if ICRRecordPtr(inst)^.instance <> nil then begin
  231.             ICDeletePref := ICCDeletePref(ICRRecordPtr(inst)^.instance, key);
  232.         end
  233.         else begin
  234.             ICDeletePref := ICRDeletePref(ICRRecordPtr(inst)^, key);
  235.         end; (* if *)
  236.     end; (* ICDeletePref *)
  237.     
  238.     function ICEnd (inst: ICInstance): ICError;
  239.     begin
  240.         if ICRRecordPtr(inst)^.instance <> nil then begin
  241.             ICEnd := ICCEnd(ICRRecordPtr(inst)^.instance);
  242.         end
  243.         else begin
  244.             ICEnd := ICREnd(ICRRecordPtr(inst)^);
  245.         end; (* if *)
  246.     end; (* ICEnd *)
  247.  
  248.     function ICDefaultFileName (inst: ICInstance; var name: Str63): ICError;
  249.     begin
  250.         if ICRRecordPtr(inst)^.instance <> nil then begin
  251.             ICDefaultFileName := ICCDefaultFileName(ICRRecordPtr(inst)^.instance, name);
  252.         end
  253.         else begin
  254.             ICDefaultFileName := ICRDefaultFileName(ICRRecordPtr(inst)^, name);
  255.         end; (* if *)
  256.     end; (* ICDefaultFileName *)
  257.  
  258.     function ICGetComponentInstance (inst: ICInstance; var component_inst: univ Ptr): ICError;
  259.     begin
  260.         component_inst := Ptr(ICRRecordPtr(inst)^.instance);
  261.         if component_inst = nil then begin
  262.             ICGetComponentInstance := badComponentInstance;
  263.         end
  264.         else begin
  265.             ICGetComponentInstance := noErr;
  266.         end; (* if *)
  267.     end; (* ICGetComponentInstance *)
  268.  
  269. end. (* ICAPI *)